<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>clipboard manual page - Tk Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tk Commands</a> <small>&gt;</small> clipboard</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
clipboard &mdash; Manipulate Tk clipboard
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>clipboard </B><I>option</I> ?<I>arg arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command provides a Tcl interface to the Tk clipboard,
which stores data for later retrieval using the selection mechanism
(via the <B>-selection CLIPBOARD</B> option).
In order to copy data into the clipboard, <B>clipboard clear</B> must
be called, followed by a sequence of one or more calls to <B>clipboard
append</B>.  To ensure that the clipboard is updated atomically, all
appends should be completed before returning to the event loop.
<P>
The first argument to <B>clipboard</B> determines the format of the
rest of the arguments and the behavior of the command.  The following
forms are currently supported:
<P>
<DL class="description">
<DT><A NAME="M5"><B>clipboard append</B> ?<B>-displayof</B> <I>window</I>? ?<B>-format</B> <I>format</I>? ?<B>-type</B> <I>type</I>? ?<B>--</B>? <I>data</I></A><DD>
Appends <I>data</I> to the clipboard on <I>window</I>'s
display in the form given by <I>type</I> with the representation given
by <I>format</I> and claims ownership of the clipboard on <I>window</I>'s
display.
<P>
<I>Type</I> specifies the form in which the selection is to be returned
(the desired
&ldquo;target&rdquo;
for conversion, in ICCCM terminology), and
should be an atom name such as <B>STRING</B> or <B>FILE_NAME</B>; see the
Inter-Client Communication Conventions Manual for complete details.
<I>Type</I> defaults to <B>STRING</B>.
<P>
The <I>format</I> argument specifies the representation that should be
used to transmit the selection to the requester (the second column of
Table 2 of the ICCCM), and defaults to <B>STRING</B>.  If <I>format</I> is
<B>STRING</B>, the selection is transmitted as 8-bit ASCII characters.  If
<I>format</I> is <B>ATOM</B>, then the <I>data</I> is
divided into fields separated by white space; each field is converted
to its atom value, and the 32-bit atom value is transmitted instead of
the atom name.  For any other <I>format</I>,  <I>data</I> is divided
into fields separated by white space and each
field is converted to a 32-bit integer; an array of integers is
transmitted to the selection requester.  Note that strings passed to
<B>clipboard append</B> are concatenated before conversion, so the
caller must take care to ensure appropriate spacing across string
boundaries.  All items appended to the clipboard with the same
<I>type</I> must have the same <I>format</I>.
<P>
The <I>format</I> argument is needed only for compatibility with
clipboard requesters that do not use Tk.  If the Tk toolkit is being
used to retrieve the <B>CLIPBOARD</B> selection then the value is
converted back to a string at the requesting end, so <I>format</I> is
irrelevant.
<P>A <B>--</B> argument may be specified to mark the end of options:  the
next argument will always be used as <I>data</I>.
This feature may be convenient if, for example, <I>data</I> starts
with a <B>-</B>.
<P><DT><A NAME="M6"><B>clipboard clear</B> ?<B>-displayof</B> <I>window</I>?</A><DD>
Claims ownership of the clipboard on <I>window</I>'s display and removes
any previous contents.  <I>Window</I> defaults to
&ldquo;.&rdquo;.
Returns an empty string.
<P><DT><A NAME="M7"><B>clipboard get</B> ?<B>-displayof</B> <I>window</I>? ?<B>-type</B> <I>type</I>?</A><DD>
Retrieve data from the clipboard on <I>window</I>'s display.
<I>Window</I> defaults to
&ldquo;.&rdquo;.
<I>Type</I> specifies the form in which
the data is to be returned and should be an atom name such as <B>STRING</B>
or <B>FILE_NAME</B>.  <I>Type</I> defaults to <B>STRING</B>.  This command is
equivalent to
&ldquo;<B><A HREF="../TkCmd/selection.htm">selection get</A></B> <B>-selection CLIPBOARD</B>&rdquo;.
<P>
Note that on modern X11 systems, the most useful type to retrieve for
transferred strings is not <B>STRING</B>, but rather <B>UTF8_STRING</B>.
<P></DL>
<H3><A NAME="M8">EXAMPLES</A></H3>
Get the current contents of the clipboard.
<PRE>if {[catch {<B>clipboard get</B>} contents]} {
    # There were no clipboard contents at all
}</PRE>
<P>
Set the clipboard to contain a fixed string.
<PRE><B>clipboard clear</B>
<B>clipboard append</B> &quot;some fixed string&quot;</PRE>
<P>
You can put custom data into the clipboard by using a custom <B>-type</B>
option. This is not necessarily portable, but can be very useful. The
method of passing Tcl scripts this way is effective, but should be mixed
with safe interpreters in production code.
<PRE># This is a very simple canvas serializer;
# it produces a script that recreates the item(s) when executed
proc getItemConfig {canvas tag} {
   set script {}
   foreach item [$canvas find withtag $tag] {
      append script {$canvas create } [$canvas type $item]
      append script { } [$canvas coords $item] { }
      foreach config [$canvas itemconf $item] {
         lassign $config name - - - value
         append script [list $name $value] { }
      }
      append script &#92;n
   }
   return [string trim $script]
}

# Set up a binding on a canvas to cut and paste an item
set c [canvas .c]
pack $c
$c create text 150 30 -text &quot;cut and paste me&quot;
bind $c &lt;&lt;Cut&gt;&gt; {
   <B>clipboard clear</B>
   <B>clipboard append -type</B> TkCanvasItem &#92;
         [getItemConfig %W current]
   # Delete because this is cut, not copy.
   %W delete current
}
bind $c &lt;&lt;Paste&gt;&gt; {
   catch {
      set canvas %W
      eval [<B>clipboard get -type</B> TkCanvasItem]
   }
}</PRE>
<H3><A NAME="M9">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/interp.htm">interp</A></B>, <B><A HREF="../TkCmd/selection.htm">selection</A></B>
<H3><A NAME="M10">KEYWORDS</A></H3>
<A href="../Keywords/C.htm#clear">clear</A>, <A href="../Keywords/F.htm#format">format</A>, <A href="../Keywords/C.htm#clipboard">clipboard</A>, <A href="../Keywords/A.htm#append">append</A>, <A href="../Keywords/S.htm#selection">selection</A>, <A href="../Keywords/T.htm#type">type</A>
<div class="copy">Copyright &copy; 1994 The Regents of the University of California.
<BR>Copyright &copy; 1994-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
